Inside Macintosh: QuickTime
This section describes the functions that allow your application to manipulate the parameters that control sequence compression and to get information about memory that the compressor has allocated. You can use these functions during the sequence-compression process. Your application establishes the default value for most of these parameters with the CompressSequenceBegin function (described on CompressSequenceBegin ). Some of these functions deal with parameter values that cannot be set when starting a sequence.
You can determine the location of the previous image buffer used by the Image Compression Manager by calling the GetCSequencePrevBuffer function.
You can set a number of compression parameters. Use the SetCSequenceFlushProc function to assign a data-unloading function to the operation. You can set the rate at which the Image Compression Manager inserts key frames into the compressed sequence by calling the SetCSequenceKeyFrameRate function. You can set the frame against which the compressor compares a frame when performing temporal compression by calling the SetCSequencePrev function. Finally, you can control the quality of the compressed image by calling the SetCSequenceQuality function.
The SetCSequenceQuality function allows you to adjust the spatial or temporal quality for the current sequence.
pascal OSErr SetCSequenceQuality (ImageSequence seqID,
CodecQ spatialQuality,
CodecQ temporalQuality);
The spatial quality parameter indicates the image quality you desire for each frame in the sequence, which governs the level of spatial compression that the compressor may apply to each frame. The temporal quality parameter indicates the sequence quality you desire, which in turn governs the amount of temporal compression that the compressor may apply to the sequence. The new quality parameters take effect with the next frame in the sequence.
You set the default spatial and temporal quality values for a sequence with the spatialQuality and temporalQuality parameters to the CompressSequenceBegin function. For details on CompressSequenceBegin , see CompressSequenceBegin .
If you change the quality settings while processing an image sequence, you affect the maximum image size that you may receive during sequence compression. Consequently, you should call the GetMaxCompressionSize function (described on GetMaxCompressionSize ) after you change the quality settings. If the maximum size has increased, you should reallocate your image buffers to accommodate the larger image size.
The SetCSequenceKeyFrameRate function adjusts the key frame rate for the current sequence.
pascal OSErr SetCSequenceKeyFrameRate (ImageSequence seqID,
long keyframerate);
The key frame rate for a sequence specifies the maximum number of frames allowed between key frames. Key frames provide points from which a temporally compressed sequence may be decompressed. The new key frame rate takes effect with the next image in the sequence. See "Defining Key Frame Rates" for more information about key frames.
You set the default key frame rate for a sequence with the keyFrameRate parameter to the CompressSequenceBegin function (described on CompressSequenceBegin ).
The GetCSequenceKeyFrameRate function lets you determine the current key frame rate of a sequence.
pascal OSErr GetCSequenceKeyFrameRate (ImageSequence seqID,
long *keyframerate);
The SetCSequenceFrameNumber function informs the compressor in use for the specified sequence that frames are being compressed out of order.
pascal OSErr SetCSequenceFrameNumber (ImageSequence seqID,
long frameNumber);
The GetCSequenceFrameNumber function returns the current frame number of the specified sequence.
pascal OSErr GetCSequenceFrameNumber (ImageSequence seqID,
long *frameNumber);
The SetCSequencePrev function allows the application to set the pixel map and boundary rectangle used by the previous frame in temporal compression. This is useful if the application that is compressing has multiple buffers and wants to update the previous frame by switching buffer pointers instead of copying the data. Usually, the Image Compression Manager allocates the previous buffer for temporal compression. Under normal circumstances, the compressor component or the Image Compression Manager updates the contents of the buffer by copying each frame into the buffer after it is compressed.
This is a very specialized function--your application should not need to call it under most circumstances.
pascal OSErr SetCSequencePrev (ImageSequence seqID,
PixMapHandle prev,
const Rect *prevRect);
When you start compressing a sequence, you may assign a previous frame buffer and rectangle with the prev and prevRect parameters to the CompressSequenceBegin function, respectively. If you specified a nil value for the prev parameter, the compressor allocates an offscreen buffer for the previous frame. In either case you may use this function to assign a new previous frame buffer.
The SetCSequenceFlushProc function lets you assign a data-unloading function to a sequence.
pascal OSErr SetCSequenceFlushProc (ImageSequence seqID,
ICMFlushProcRecordPtr flushProc,
long bufferSize);
Data-unloading functions allow compressors to work with images that cannot fit in memory. During the compression operation, the compressor calls the data-unloading function whenever it has accumulated a specified amount of compressed data. Your data-unloading function then writes the compressed data to some other device, freeing buffer space for more compressed data. The compressor starts using the data-unloading function with the next image in the sequence. See "Spooling Compressed Data" for more information.
There is no parameter to the CompressSequenceBegin function (described on CompressSequenceBegin ) that allows you to assign a data-unloading function to a sequence.
The GetCSequencePrevBuffer function determines the location of the previous image buffer allocated by the compressor.
pascal OSErr GetCSequencePrevBuffer (ImageSequence seqID,
GWorldPtr *gworld);
If you do not specify a previous image buffer with the prev parameter to the CompressSequenceBegin function, the compressor allocates an offscreen graphics world for you. Your program can obtain access to the pixel map in that graphics world by calling this function.
Note that the GetCSequencePrevBuffer function only returns information about buffers that were allocated by the compressor. You cannot use this function to determine the location of a buffer you have provided.